<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <link rel="shortcut icon" href="../../img/favicon.ico" />
    <title>插件 - GCTG SoftWare</title>
    <link rel="stylesheet" href="../../css/theme.css" />
    <link rel="stylesheet" href="../../css/theme_extra.css" />
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
        <link href="../../css/extra.css" rel="stylesheet" />
    
      <script>
        // Current page data
        var mkdocs_page_name = "\u63d2\u4ef6";
        var mkdocs_page_input_path = "user-guide\\plugins.md";
        var mkdocs_page_url = null;
      </script>
    
    <script src="../../js/jquery-3.6.0.min.js" defer></script>
    <!--[if lt IE 9]>
      <script src="../../js/html5shiv.min.js"></script>
    <![endif]-->
      <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
      <script>hljs.initHighlightingOnLoad();</script> 
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
    <div class="wy-side-scroll">
      <div class="wy-side-nav-search">
          <a href="../.." class="icon icon-home"> GCTG SoftWare
        </a><div role="search">
  <form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
      <input type="text" name="q" placeholder="Search docs" title="Type search term here" />
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul>
                <li class="toctree-l1"><a class="reference internal" href="../..">主页</a>
                </li>
              </ul>
              <p class="caption"><span class="caption-text">用户指南</span></p>
              <ul class="current">
                  <li class="toctree-l1"><a class="reference internal" href="../writing-your-docs/">开发文档</a>
                  </li>
                  <li class="toctree-l1"><a class="reference internal" href="../styling-your-docs/">设置文档样式</a>
                  </li>
                  <li class="toctree-l1"><a class="reference internal" href="../configuration/">配置文件</a>
                  </li>
                  <li class="toctree-l1"><a class="reference internal" href="../deploying-your-docs/">部署文档</a>
                  </li>
                  <li class="toctree-l1 current"><a class="reference internal current" href="./">插件</a>
    <ul class="current">
    <li class="toctree-l2"><a class="reference internal" href="#_1">安装插件</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#_2">使用插件</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#_3">开发插件</a>
        <ul>
    <li class="toctree-l3"><a class="reference internal" href="#baseplugin">BasePlugin</a>
        <ul>
    <li class="toctree-l4"><a class="reference internal" href="#config_scheme">config_scheme</a>
    </li>
    <li class="toctree-l4"><a class="reference internal" href="#config">config</a>
    </li>
    <li class="toctree-l4"><a class="reference internal" href="#load_configoptions">load_config(options)</a>
    </li>
    <li class="toctree-l4"><a class="reference internal" href="#on_event_name">on_&lt;event_name&gt;()</a>
    </li>
        </ul>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#_4">事件</a>
        <ul>
    <li class="toctree-l4"><a class="reference internal" href="#_5">全局事件</a>
    </li>
    <li class="toctree-l4"><a class="reference internal" href="#_6">模板事件</a>
    </li>
    <li class="toctree-l4"><a class="reference internal" href="#_7">页面事件</a>
    </li>
        </ul>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#entry-point">Entry Point</a>
    </li>
        </ul>
    </li>
    </ul>
                  </li>
              </ul>
              <p class="caption"><span class="caption-text">关于</span></p>
              <ul>
                  <li class="toctree-l1"><a class="reference internal" href="../../about/release-notes/">发行说明</a>
                  </li>
                  <li class="toctree-l1"><a class="reference internal" href="../../about/license/">许可</a>
                  </li>
              </ul>
      </div>
    </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
      <nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../..">GCTG SoftWare</a>
        
      </nav>
      <div class="wy-nav-content">
        <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="../.." class="icon icon-home" alt="Docs"></a> &raquo;</li>
          <li>用户指南 &raquo;</li>
      <li>插件</li>
    <li class="wy-breadcrumbs-aside">
    </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div class="section" itemprop="articleBody">
              
                <h1 id="mkdocs">MkDocs插件</h1>
<p>安装，使用和创建MkDocs插件的指南</p>
<hr />
<h2 id="_1">安装插件</h2>
<p>在使用插件之前，必须将其安装在系统上。 如果您使用的是MkDocs附带的插件，则在安装MkDocs时会安装它。 但是，要安装第三方插件，您需要确定相应的软件包名称并使用<code>pip</code>进行安装：</p>
<pre><code class="language-bash">pip install mkdocs-foo-plugin
</code></pre>
<p>插件成功安装后即可使用。 它只需要在配置文件中<a href="＃using-plugins">启用</a>。</p>
<h2 id="_2">使用插件</h2>
<p><a href="../configuration/#plugins"><code>plugins</code></a>配置选项应包含构建站点时要使用的插件列表。 每个“插件”必须是分配给插件的字符串名称（请参阅给定插件的文档以确定其“名称”）。 此处列出的插件必须已经<a href="#instalting-plugins">安装</a>。</p>
<pre><code class="language-yaml">plugins:
    - search
</code></pre>
<p>某些插件可能提供自己的配置选项。 如果要设置任何配置选项，则可以嵌套给定插件支持的任何选项的键/值映射（<code>option_name：option value</code>）。请注意冒号（<code>：</code>）必须遵循插件名称，然后在新行上，选项名称和值必须缩进并用冒号分隔。如果要为单个插件定义多个选项，则必须在单独的行上定义每个选项。</p>
<pre><code class="language-yaml">plugins:
    - search:
        lang: en
        foo: bar
</code></pre>
<p>有关给定插件可用配置选项的信息，请参阅该插件的文档。</p>
<p>有关默认插件的列表以及如何覆盖它们，请参阅<a href="../configuration/#plugins">配置文件</a>文档。</p>
<h2 id="_3">开发插件</h2>
<p>像MkDocs一样，插件必须用Python编写。 通常期望每个插件将作为单独的Python模块分发，尽管可以在同一模块中定义多个插件。 至少，MkDocs插件必须由<a href="#baseplugin">BasePlugin</a>子类和指向它的<a href="#entry-point">entry point</a>组成。</p>
<h3 id="baseplugin">BasePlugin</h3>
<p><code>mkdocs.plugins.BasePlugin</code>的子类应该定义插件的行为。该类通常包括对构建过程中的特定事件执行的操作以及插件的配置方案。</p>
<p>所有<code>BasePlugin</code>子类都包含以下属性：</p>
<h4 id="config_scheme">config_scheme</h4>
<p>:   配置验证实例的元组。 每个项目必须包含一个两项元组，其中第一项是配置选项的字符串名称，第二项是<code>mkdocs.config.config_options.BaseConfigOption</code>或其任何子类的实例。</p>
<pre><code>例如，以下`config_scheme`定义了三个配置选项：`foo`，它接受一个字符串; `bar`，接受一个整数; 和`baz`，它接受一个布尔值。

    class MyPlugin(mkdocs.plugins.BasePlugin):
        config_scheme = (
            ('foo', mkdocs.config.config_options.Type(mkdocs.utils.string_types, default='a default value')),
            ('bar', mkdocs.config.config_options.Type(int, default=0)),
            ('baz', mkdocs.config.config_options.Type(bool, default=True))
        )

加载用户配置后，将使用上述方案验证配置并填写用户未提供的设置的任何默认值。验证类可以是`mkdocs.config.config_options`中提供的任何类，也可以是插件中定义的第三方子类。

用户提供的任何验证失败或未在`config_scheme`中定义的设置都会引发`mkdocs.config.base.ValidationError`。
</code></pre>
<h4 id="config">config</h4>
<p>:   插件的配置选项字典，在配置验证完成后由<code>load_config</code>方法填充。 使用此属性可以访问用户提供的选项。</p>
<pre><code>    def on_pre_build(self, config):
        if self.config['bool_option']:
            # implement "bool_option" functionality here...
</code></pre>
<p>所有<code>BasePlugin</code>子类都包含以下方法：</p>
<h4 id="load_configoptions">load_config(options)</h4>
<p>:   从选项字典加载配置。 返回<code>（错误，警告）</code>的元组。MkDocs在配置验证期间调用此方法，并且不需要由插件调用。</p>
<h4 id="on_event_name">on_&lt;event_name&gt;()</h4>
<p>:   定义特定[事件]行为的可选方法。 插件应该在这些方法中定义它的行为。 将<code>&lt;event_name&gt;</code>替换为事件的实际名称。 例如，<code>pre_build</code>事件将在<code>on_pre_build</code>方法中定义。</p>
<pre><code>大多数事件接受一个位置参数和各种关键字参数。 通常期望插件修改（或替换）位置参数并返回。 如果没有返回任何内容（该方法返回“None”），则使用原始未修改的对象。简单地提供关键字参数以提供可用于确定如何修改位置参数的上下文和/或供应数据。 接受关键字参数为“** kwargs”是一种好习惯。如果在未来版本的MkDocs中为事件提供了其他关键字，则无需更改您的插件。

例如，以下事件会向主题配置添加额外的static_template：

    class MyPlugin(BasePlugin):
        def on_config(self, config, **kwargs):
            config['theme'].static_templates.add('my_template.html')
            return config
</code></pre>
<h3 id="_4">事件</h3>
<p>有三种事件：[全局事件]，[页面事件]和[模板事件]。</p>
<h4 id="_5">全局事件</h4>
<p>在构建过程的开始或结束时，每个构建都会调用一次全局事件。在这些事件中所做的任何更改都将对整个站点产生全局影响。</p>
<h5 id="on_serve">on_serve</h5>
<p>:   只有在开发过程中使用<code>serve</code>命令时才会调用<code>serve</code>事件。 它传递给<code>Server</code>实例，可以在激活之前进行修改。 例如，可以将附加文件或目录添加到“监视”文件列表中以进行自动重新加载。</p>
<pre><code>Parameters:
: __server:__ `livereload.Server`的实例
: __config:__ 全局配置对象

Returns:
: `livereload.Server`的实例
</code></pre>
<h5 id="on_config">on_config</h5>
<p>:   <code>config</code>事件是第一个在构建时调用的事件，在加载和验证用户配置后立即运行。 应在此处对配置进行任何更改。</p>
<pre><code>Parameters:
: __config:__ 全局配置对象

Returns:
: 全局配置对象
</code></pre>
<h5 id="on_pre_build">on_pre_build</h5>
<p>:   <code>pre_build</code>事件不会改变任何变量。 使用此事件可以调用预构建脚本。</p>
<pre><code>Parameters:
: __config:__ 全局配置对象
</code></pre>
<h5 id="on_files">on_files</h5>
<p>:   从<code>docs_dir</code>填充文件集合后调用<code>files</code>事件。 使用此事件可以添加，删除或更改集合中的文件。 请注意，Page对象尚未与集合中的文件对象关联。 使用[页面事件]来处理页面特定数据。</p>
<pre><code>Parameters:
: __files:__ 全局配置对象
: __config:__ 全局配置对象

Returns:
: 全局文件集合
</code></pre>
<h5 id="on_nav">on_nav</h5>
<p>:   创建站点导航后会调用<code>nav</code>事件，并可用于更改站点导航。</p>
<pre><code>Parameters:
: __nav:__ 全局导航对象
: __config:__ 全局配置对象
: __files:__ 全局文件集合

Returns:
: 全局导航对象
</code></pre>
<h5 id="on_env">on_env</h5>
<p>:   在创建Jinja模板环境之后调用<code>env</code>事件，并且可以使用它来改变Jinja环境。</p>
<pre><code>Parameters:
: __env:__ 全局Jinja环境
: __config:__ 全局配置对象
: __files:__ 全局文件集合

Returns:
: 全局Jinja环境
</code></pre>
<h5 id="on_post_build">on_post_build</h5>
<p>:   <code>post_build</code>事件不会改变任何变量。 使用此事件来调用构建后脚本。</p>
<pre><code>Parameters:
: __config:__ 全局配置对象
</code></pre>
<h4 id="_6">模板事件</h4>
<p>为每个非页面模板调用一次模板事件。 将为<a href="../configuration/#extra_templates">extra_templates</a>配置设置中定义的每个模板以及主题中定义的任何<a href="../configuration/#static_templates">static_templates</a>调用每个模板事件。 所有模板事件在<a href="#on_env">env</a>事件之后和任何[页面事件]之前调用。</p>
<h5 id="on_pre_template">on_pre_template</h5>
<p>:   加载主题模板后立即调用<code>pre_template</code>事件，可用于更改模板的内容。</p>
<pre><code>Parameters:
: __template__: 模板内容为字符串
: __template_name__: 模板的字符串文件名
: __config:__ 全局配置对象

Returns:
: 模板内容为字符串
</code></pre>
<h5 id="on_template_context">on_template_context</h5>
<p>:   在为主题模板创建上下文之后立即调用<code>template_context</code>事件，并且可以仅使用该事件来更改该特定模板的上下文。</p>
<pre><code>Parameters:
: __context__: 模板上下文变量的字典
: __template_name__: 模板的字符串文件名
: __config:__ 全局配置对象

Returns:
: 模板上下文变量的字典
</code></pre>
<h5 id="on_post_template">on_post_template</h5>
<p>:   <code>post_template</code>事件在渲染模板后调用，但在写入光盘之前调用，可用于更改模板的输出。如果返回空字符串，则跳过该模板，并且没有任何内容写入光盘。</p>
<pre><code>Parameters:
: __output_content__: 将呈现的模板输出为字符串
: __template_name__: 模板的字符串文件名
: __config:__ 全局配置对象

Returns:
: 将呈现的模板输出为字符串
</code></pre>
<h4 id="_7">页面事件</h4>
<p>对于网站中包含的每个Markdown页面，都会调用一次页面事件。 所有页面事件在<a href="#on_post_template">post_template</a>事件之后和<a href="#on_post_build">post_build</a>事件之前调用。</p>
<h5 id="on_pre_page">on_pre_page</h5>
<p>:   在对主题页面执行任何操作之前调用<code>pre_page</code>事件，并且可以使用它来更改<code>Page</code>实例。</p>
<pre><code>Parameters:
: __page:__ `mkdocs.nav.Page` 的实例
: __config:__ 全局配置对象
: __files:__ 全局文件集合

Returns:
: `mkdocs.nav.Page` 实例
</code></pre>
<h5 id="on_page_read_source">on_page_read_source</h5>
<p>:   <code>on_page_read_source</code>事件可以替换默认机制，以从文件系统中读取页面源的内容。</p>
<pre><code>Parameters:
: __page:__ `mkdocs.nav.Page`实列
: __config:__ 全局配置对象

Returns:
: 页面的原始源作为unicode字符串。 如果返回“None”，则将执行文件的默认加载。
</code></pre>
<h5 id="on_page_markdown">on_page_markdown</h5>
<p>:   在从文件加载页面标记后，调用<code>page_markdown</code>事件，可用于更改Markdown源文本。元数据已被剥离，此时可以作为“page.meta”使用。</p>
<pre><code>Parameters:
: __markdown:__ Markdown源文本作为字符串
: __page:__ `mkdocs.nav.Page`实例
: __config:__ 全局配置对象
: __files:__ 全局文件集合

Returns:
: Markdown源文本作为字符串
</code></pre>
<h5 id="on_page_content">on_page_content</h5>
<p>:   在将Markdown文本呈现为HTML（但在传递给模板之前）之后调用<code>page_content</code>事件，并且可以使用该事件来更改页面的HTML主体。</p>
<pre><code>Parameters:
: __html:__ 从Markdown源呈现的HTML作为字符串
: __page:__ `mkdocs.nav.Page`实例
: __config:__ 全局配置对象
: __files:__ 全局文件集合

Returns:
: 从Markdown源呈现的HTML作为字符串
</code></pre>
<h5 id="on_page_context">on_page_context</h5>
<p>:   在创建页面的上下文之后调用<code>page_context</code>事件，并且该事件可用于仅更改该特定页面的上下文。</p>
<pre><code>Parameters:
: __context__: 模板上下文变量的字典
: __page:__ `mkdocs.nav.Page`实例
: __config:__ 全局配置对象
: __nav:__ 全局导航对象

Returns:
: 模板上下文变量的字典
</code></pre>
<h5 id="on_post_page">on_post_page</h5>
<p>:   在呈现模板之后，但在将其写入光盘之前调用<code>post_page</code>事件，并且可以使用该事件来改变页面的输出。 如果返回空字符串，则跳过该页面并且不会将任何内容写入光盘。</p>
<pre><code>Parameters:
: __output:__ 将呈现的模板输出为字符串
: __page:__ `mkdocs.nav.Page`实例
: __config:__ 全局配置对象

Returns:
: 将呈现的模板输出为字符串
</code></pre>
<h3 id="entry-point">Entry Point</h3>
<p>插件需要打包为Python库（分布在PyPI上，与MkDocs分开），每个插件必须通过setuptools entry_point注册为插件。 将以下内容添加到<code>setup.py</code>脚本中：</p>
<pre><code class="language-python">entry_points={
    'mkdocs.plugins': [
        'pluginname = path.to.some_plugin:SomePluginClass',
    ]
}
</code></pre>
<p><code>pluginname</code>将是用户使用的名称（在配置文件中）；<code>path.to.some_plugin：SomePluginClass</code>将是可导入的插件本身（<code>from path.to.some_plugin import SomePluginClass</code>）其中<code>SomePluginClass</code>是 <a href="#baseplugin">BasePlugin</a>的子类，定义插件行为。 当然，多个插件类可以存在于同一个模块中。 只需将每个定义为单独的entry_point即可。</p>
<pre><code class="language-python">entry_points={
    'mkdocs.plugins': [
        'featureA = path.to.my_plugins:PluginA',
        'featureB = path.to.my_plugins:PluginB'
    ]
}
</code></pre>
<p>请注意，注册插件不会激活它。 如果通过配置，用户仍然需要告诉MkDocs使用。</p>
              
            </div>
          </div><footer>
    <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
        <a href="../deploying-your-docs/" class="btn btn-neutral float-left" title="部署文档"><span class="icon icon-circle-arrow-left"></span> Previous</a>
        <a href="../../about/release-notes/" class="btn btn-neutral float-right" title="发行说明">Next <span class="icon icon-circle-arrow-right"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
  </div>

  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
          
        </div>
      </div>

    </section>

  </div>

  <div class="rst-versions" role="note" aria-label="Versions">
  <span class="rst-current-version" data-toggle="rst-current-version">
    
    
      <span><a href="../deploying-your-docs/" style="color: #fcfcfc">&laquo; Previous</a></span>
    
    
      <span><a href="../../about/release-notes/" style="color: #fcfcfc">Next &raquo;</a></span>
    
  </span>
</div>
    <script>var base_url = '../..';</script>
    <script src="../../js/theme_extra.js" defer></script>
    <script src="../../js/theme.js" defer></script>
      <script src="../../search/main.js" defer></script>
    <script defer>
        window.onload = function () {
            SphinxRtdTheme.Navigation.enable(true);
        };
    </script>

</body>
</html>
